feat(query): add restore and restorePages to undo drop - #342

Why

$data(key, value, undo) lets a write take back only its own change, but the function that undoes a removal from a list had to be written by hand in every app: find the item in the previous data, put it back where it stood, and leave the list alone if a refetch has already brought it back. A plain revert does not fit here: it brings the whole list back and drops what was written since, such as an item added while the removal was in flight.

What

• restore(array, prev, what) puts values removed with drop back at their previous indexes in the current array. It takes back every match, since drop removes them all, and leaves an array that holds a matching value again as it is, so nothing comes back twice.
• restorePages(pages, prev, what, callback) does the same for infinite pages, each page from the page with the same number in prev. The callback adapts the page shape, as in sortPages. Pages stay as they are when a matching item is back on any page, and a page that is no longer loaded gets nothing back.
• Both take the data as $data passes it to undo, null included.
• Docs: the helpers in Cache Mutation Helpers, with a note to wrap the result in sort or sortPages when the client knows the order of the list, an example next to undo in Reading and Writing Data, and a point in the nano-kit-query skill, with its DOCS.md regenerated.

Size

Only code that imports the helpers pays for them: restore adds 52 B on top of drop, restorePages adds 125 B on top of mapPages and drop.

An item goes back to its previous index, so one added in the meantime can shift it by a place. Matching neighbours with an id selector closes that, but makes restore two and a half times heavier, and a list with a known order gets the exact place from sort and sortPages anyway.

Tests

utils.spec.ts: one value and several values put back, what was written since, an array that became shorter or empty, no mutation of the input, a value that is back already, empty values, and for pages the page an item stood in, the pagination of the current pages, items of several pages, a custom page shape, an item back on another page, a page loaded since and a page no longer loaded. cache.spec.ts: both helpers as the undo of a real $data write. oxlint, tsc and vitest are clean in @nano_kit/query (214 tests), size-limit passes, the pre-push pnpm test passes across the monorepo and the website builds.